fix(app-shell): a failed managed-snapshot refresh is not a current record (objectui#7907) - #7937

Fixes #7907

The defect

The tail of onManageChanged — the managed-snapshot refresh that runs after every
lifecycle action fired from the PackageDetailSheet (disable / enable / duplicate /
publish / publish-drafts / manifest edit) — was:

try {
  const fresh = await fetchFullPackage(managedId);
  if (fresh) setManage(fresh);
} catch {
  /* keep the current snapshot */
}

The comment is true of what it did, and it is the reason it was wrong. The record in
manage is already known to be out of date at that point: the action the author
just fired is what changed it, and this read is what replaces it. So the author disabled
a package, was told nothing, and went on reading Status: Enabled — the pre-action
record presented as current.

⭐ #7881 did not introduce this — it made this arm swallow MORE

Fixing one swallowed-error defect makes another swallowing site swallow more. Before
objectui#7881 (PR #7906) fetchFullPackage never read res.ok, so this catch could
only ever see a res.json() rejection — a non-JSON body. Now that the helper refuses a
non-2xx, the same catch also swallowed every 401 / 403 / 503 / 500 the endpoint
serves. ⛔ Not a regression from #7906: a pre-existing defect that #7906 made much
easier to hit. A reader who meets this card without that sentence will conclude the
opposite.

The response shapes, measured on THIS arm

⛔ Not taken from #7881 on trust — re-measured at the producer, because this arm reads
fetchFullPackage and could have taken a different path. It does not: it is
GET /api/v1/packages, served by the direct-mount registrar
(@objectstack/rest package-routes.ts). Its list handler contains no hand-written
body — success leaves through sendOk, every failure through sendError /
sendThrownError, and sendError writes exactly
{ success: false, error: { code, message, ...extra } }.

Two of those are additions to #7881's table rather than restatements of it, and both are
specific to this arm: it runs immediately after a mutating request, which is when a
transport drop is most likely, and it is reached with a package id that a concurrent
delete can have removed.

The 400 VALIDATION_ERROR of the sibling /packages/:id routes is not reachable
here: it comes from repeated query parameters, and this call sends no query string.

One shape measured and NOT covered, reported as asked. Since the framework's #12502
this door also emits error.userMessage — text a producer marked at throw time as
addressed to the end user, which ADR-0112 tells a consumer to render verbatim.
fetchFullPackage reads only error.message and error.code, so on a 5xx it shows the
withheld generic sentence and drops the producer's marked one. That read is
fetchFullPackage's, i.e. #7906's surface and shared by all four of its callers, not
this card's tail — filed separately rather than fixed here.

The fix

1. Reported through this file's existing posture, not a second one —
   formatMetadataError on the shared studio-package-list sonner id. One outage
   rejects both halves of this callback and both report on that id, so it stays one
   toast rather than a stack. ⛔ No new state machine, no new channel.
2. The sheet closes rather than present the pre-action record as current.
3. fresh === null is reported too — a successful read whose list no longer contains
   the package was dropped by if (fresh) just as quietly as the catch dropped a
   throw. It now says so with the sentence openManage already uses for exactly that
   fact (engine.studio.pkg.manageMissing).

Why closing, and why it is not "just close it"

PackageDetailSheet is an action surface, and it derives its verb from the record it
was handed: enabled = pkg.enabled !== false && pkg.status !== 'disabled' picks both the
button's label and the endpoint it POSTs (.../${enabled ? 'disable' : 'enable'},
PackagesPage.tsx lines 308 / 500 / 650). Left open over a snapshot known to be
pre-action it does not merely show a stale badge — it re-arms the author with the verb
they just fired: disable succeeds, the refresh fails, the button still reads "Disable"
and still POSTs /disable.

It remains a degradation, never a throw (objectui#7368's standing ruling — one 503
must not take the Studio down): the editor, the top bar and the package list all stay,
the trigger still works, and reopening the sheet re-runs this same read one click away —
which objectui#7881 taught to report its own outcome. What is deliberately not done is
the card's option 2, marking the record stale so the staleness outlives the toast: that
needs a new prop on PackageDetailSheet, which lives in metadata-admin/PackagesPage.tsx
— outside this card's file surface and a signature change under Clause-②. Raised in the
report rather than taken.

The pkgsErr slot: measured on this arm, and NOT written

#7881 ruled A (do not write it) from the in-file rule that pkgsErr is written exactly
where pkgs is, and openManage never writes pkgs. This callback does write
pkgs, so that ruling could not simply be carried over. Measured instead:

• pkgs is written at exactly two sites — the mount effect and the head of this
  callback — and pkgsErr is written at those same two sites and nowhere else.
• The tail writes neither. It writes manage.

So the relevant unit is the arm, not the callback: by the time the tail runs, the
head has already recorded the list's own verdict (a fresh list plus setPkgsErr(null),
or its failure). Writing pkgsErr from the tail would mark the trigger failed over
names the head had just refreshed successfully — objectui#7368's lie pointed the other
way. Verdict A, on this arm's own measurement, for a different reason than #7881's.

Evidence — the ablation, with predictions written first

Predictions were recorded before any leg ran. All three legs matched, in count and in
pin identity.

Leg A's red set was §1.1 §1.2 §1.3 §2.1 §2.2 §3 §4 §5.1 §5.2 with the four §6 controls
green — exactly as predicted. The load-bearing red, verbatim:

FAIL |dom| ... > §1 a 503 SERVICE_UNAVAILABLE envelope on the refresh >
             no longer presents the PRE-ACTION record as current
Error: expect(element).not.toBeInTheDocument()
expected document not to contain element, found div
  data-managed-enabled="true"
  data-managed-id="app.b2r4"
  data-managed-status="active"
  data-testid="pkg-sheet"

That is the defect itself: after a lifecycle action and a 503 on the refresh, the sheet
is still on screen holding the pre-action record (status="active",
enabled="true"), and AssertionError: expected "vi.fn()" to be called at least once
on the sibling pin says nothing was reported at all.

⭐ Legs B and C are what exclude the degenerate fixes, and they fail from opposite
sides:

• B — closing the sheet without reporting buys pin §1.2 and nothing else: all
  eight reporting pins stay red. A "fix" that merely closes cannot pass this file.
• C — closing unconditionally additionally kills §6.1 / §6.2 / §6.3, the negative
  controls, because it breaks the successful refresh. §6.4 stays green because a real
  deletion is decided by the head and never reaches the tail.

Together they pin the fix between the two ways of being wrong: report without breaking
the refresh, close without closing always.

The mutation was proved on disk before anything was read, and the restore by state:

Anchors flipped with it — leg A: manageRefreshFailed 1 to 0, keep the current snapshot 0 to 1; legs B/C: manageRefreshFailed 1 to 0 and their own marker 0 to 1.
An empty or unchanged hash aborted the leg rather than letting it be read as a result.
Leg A's blob deba94ef is the same blob PR #7906 recorded as its HEAD blob, which is
the expected cross-check: leg A restores exactly the state #7906 landed.

The script carried trap ... EXIT INT TERM restoring an absolute path, and every
restore named HEAD explicitly — git checkout ref -- path writes the index too, so a
bare git checkout -- path would have handed the mutation straight back while
git status read clean.

No rebuild leg applies: the pins import ./StudioDesignSurface by relative
specifier, so vitest transforms the .tsx source and no dist/ stands between the
mutation and the run.

Verification — all on the pushed commit e09e9857e, git diff HEAD empty

The type-check green is not vacuous: tsc -p tsconfig.test.json --listFiles contains
all three edited/added files, 1 hit each. It also needed the dependency closure built
first (pnpm --filter '@object-ui/app-shell^...' build) — without it the run was 100+
TS2307 Cannot find module @object-ui/..., the stale-dist trap, not a real red.

The gate family was derived by hand from the changed paths against package.json and
.github/workflows/ — this repo has no scripts/pm/dispatch-gates.mjs (that script
lives in objectstack and answers only about its own tree).

Lint — a measured narrowing, not a skip

The repo-wide scan is CI's run. Measured here instead:

• Population read from eslint itself, not guessed: eslint . over the whole affected
  package linted 1081 files (count from --format json), 0 errors.
• The 3 changed files on their own: 0 errors, 0 warnings on the new test file and on
  i18n.ts. The 19 warnings on StudioDesignSurface.tsx are all pre-existing — they sit
  at lines 760-4280, and every line this PR adds is in 512-590. Notably
  react-hooks/exhaustive-deps does not flag onManageChanged: locale was added to
  its dependency array with the new tFormat reads.
• Config invariance for untouched files: eslint.config.js extends
  js.configs.recommended + tseslint.configs.recommended and declares no
  parserOptions.project and no projectService (0 matches) — type-aware linting is not
  enabled, so every rule's verdict is a function of that file's own text plus the shared
  config. A diff confined to three files cannot move any untouched file's verdict.

Boundaries held

• The hard-coded /home recovery destination is untouched — that is objectui#7373.
• The head of onManageChanged is untouched (objectui#7821 / PR fix(app-shell): a failed package-list refresh is not a deletion (objectui#7821) #7879), and so is
  openManage (objectui#7881 / PR fix(app-shell): a failed package lookup is not an empty result (objectui#7881) #7906). The only removed lines in the whole diff are
  the four of the old tail.
• ⛔ No navigation was added. A snapshot this read could not deliver is not evidence
  of deletion; a successful list that lacks the package still belongs to the head, and
  §6.4 pins that it still evicts exactly as before. Reporting is not inferring.
• Clause-② holds: no export added, no signature changed, no gate touched.

Generated by Claude Code